SuiteQL Query Tool

Version 2026.1

A modern, feature-rich utility for running SuiteQL queries directly in NetSuite with a professional SQL IDE experience.

🎉

Join the SuiteQL Query Tool Community!

I've launched the SuiteQL Query Tool Community on LinkedIn. It's a place to share tips, ask questions, and connect with other users.

During the beta period, this is also the preferred way to suggest ideas, report bugs, and provide feedback.

🔗 Join the LinkedIn Group

Introduction

The SuiteQL Query Tool is a powerful NetSuite Suitelet application designed for developers, administrators, and analysts who need to query NetSuite data using SuiteQL. It provides a modern, intuitive interface inspired by professional SQL IDEs like SQL Server Management Studio and Azure Data Studio.

Developed by Tim Dietrich, this open-source tool transforms the way you interact with NetSuite's SuiteQL capabilities, offering features like syntax highlighting, auto-complete, query history, and multiple export formats.

Table of Contents

Installation

Follow these steps to install the SuiteQL Query Tool in your NetSuite account:

1

Upload the Script File

Navigate to Documents > Files > File Cabinet in NetSuite. Create a folder for your scripts (e.g., SuiteScripts/SuiteQL) and upload the suiteql-query-tool.v2026.1.suitelet.js file.

2

Create a Script Record

Go to Customization > Scripting > Scripts > New. Select the uploaded file and click Create Script Record. Fill in the details:

  • Name: SuiteQL Query Tool
  • ID: _suiteql_query_tool (or your preferred ID)
  • Script File: Select the uploaded file
3

Deploy the Script

After saving the script record, click Deploy Script. Configure the deployment:

  • Title: SuiteQL Query Tool
  • ID: _suiteql_query_tool (or your preferred ID)
  • Status: Released
  • Audience: Select the roles that should have access
  • Log Level: Error (recommended for production)
4

Access the Tool

After deployment, you can access the tool via the external URL provided in the deployment record, or by navigating to Customization > Scripting > Script Deployments and clicking the deployment link.

Tip: Bookmark the Suitelet URL for quick access, or add it to your NetSuite dashboard as a custom portlet link.

Features Overview

AI Query Generator

Describe what you need in plain English and get working SuiteQL queries instantly. Supports 7 AI providers.

Natural Language Query Bar

Quick input bar above the editor - type plain English and generate queries directly.

AI Query Explain

Click "Explain" to have AI break down complex queries into plain English.

AI Query Validation

AI reviews your query before execution, warning about potential issues.

AI Tables Reference

Ask AI about any table, find the right tables, and generate queries from selected columns.

Query Optimization

For slow queries, AI suggests indexes, better joins, and restructuring.

SQL Syntax Highlighting

CodeMirror-powered editor with full SQL syntax highlighting and line numbers.

Auto-Complete

Table and column name suggestions with Ctrl+Space for faster query writing.

Query History

Automatically saves your query history locally for easy access to previous queries.

Dark Mode

Toggle between light and dark themes for comfortable viewing in any environment.

Multiple Export Formats

Export results to Excel (.xlsx), CSV, JSON, or copy directly to clipboard.

Cloud Export

Export directly to Google Sheets or Airtable with batching and progress tracking.

Column Statistics

View SUM, AVG, MIN, and MAX for numeric columns in your results.

Query Parameters

Use {{variable}} syntax for dynamic queries with prompted input.

Query Sharing

Generate shareable URLs that include your query for easy collaboration.

Column Pinning

Freeze the first 1-3 columns while scrolling horizontally through results.

Drag & Drop Import

Import SQL files by dragging and dropping them onto the editor.

Column Reordering

Drag column headers to reorder columns in the results table.

Results Maximized

Hide the editor to view results in full-screen mode.

Data Visualization / Charts

Create bar, line, pie, doughnut, and polar area charts from query results with AI-assisted generation.

Clickable Record Links

ID columns automatically link to NetSuite records. Click to open customers, transactions, items, and more.

Plugin Architecture

Extend the tool with custom plugins. Add hooks, UI elements, and server-side processing.

Generate Suitelet

Create standalone SuiteScript Suitelets from Document Generator templates with one click.

ERD Generation

Interactive Entity Relationship Diagrams with export to SVG, PNG, and DOT formats.

Extended Schema Export

Export schemas to BigQuery, Snowflake, Redshift, dbt YAML, Avro, Markdown, and more.

Getting Started

Your First Query

When you first open the SuiteQL Query Tool, you'll see a sample query in the editor. You can modify this or write your own query. Here's a simple example to get started:

SELECT
    id,
    companyname,
    email,
    datecreated
FROM
    customer
WHERE
    isinactive = 'F'
ORDER BY
    datecreated DESC

Click the Run Query button or press Ctrl + Enter to execute the query.

Understanding the Interface

Using the Query Editor

Writing Queries

The editor supports standard SuiteQL syntax with SQL highlighting. SuiteQL is NetSuite's SQL-like query language that allows you to query NetSuite records.

Auto-Complete

Press Ctrl + Space to trigger auto-complete suggestions. The tool provides suggestions for:

Tip: Enable auto-complete from the Options panel to get suggestions as you type.

Query Parameters

Use double curly braces to create dynamic parameters in your queries:

SELECT * FROM customer
WHERE datecreated >= '{{Start Date}}'
  AND datecreated <= '{{End Date}}'

When you run the query, you'll be prompted to enter values for each parameter. The tool remembers your last-used values.

Importing SQL Files

You can import SQL files in two ways:

Undo/Redo History

Click the history icon in the toolbar to view and restore previous editor states. This is useful if you accidentally delete or modify your query.

Working with Results

View Modes

The results panel offers three view modes:

Row Details

Click any row in the results to open a detailed view showing all fields for that record. Use the arrow keys to navigate between rows while the detail view is open.

Clickable Record Links

ID columns in your results automatically become clickable links to the corresponding NetSuite records:

Column Features

Exporting Results

Click the Export button to export your results:

Results Maximized Mode

Press Shift + R or click the expand button to hide the editor and maximize the results panel. Press Esc or click the button again to restore.

Keyboard Shortcuts

Press ? at any time to view the keyboard shortcuts modal.

Action Shortcut
Run Query Ctrl + Enter
Format Query Ctrl + Shift + F
Save Query Ctrl + S
Undo Ctrl + Z
Redo Ctrl + Shift + Z
Auto-Complete Ctrl + Space
Maximize Results Shift + R
Exit Focus/Maximized Mode Esc
Previous Row (in details) ←
Next Row (in details) →
Show Shortcuts ?
Note: On Mac, use Cmd instead of Ctrl.

Advanced Features

Query Library

Access the built-in Query Library from the toolbar to browse pre-built queries for common NetSuite tasks. These queries serve as useful examples and starting points for your own queries.

Tables Reference

Click Tables Reference in the toolbar to open a new window with a searchable list of all NetSuite tables available for querying.

Focus Mode

Click the Focus Mode button (expand arrows icon) in the header to hide the NetSuite navigation and maximize your workspace. Combined with Results Maximized mode, you can dedicate your entire screen to query results.

Query Sharing

Click Share in the toolbar to generate a URL that includes your current query. Anyone with access to the Suitelet can use this URL to open the tool with your query pre-loaded.

Auto-Save Draft

Your current query is automatically saved to local storage as you type. If you accidentally close the browser or navigate away, your query will be restored when you return.

Execution Time Tracking

The tool tracks execution times for your queries, displayed in the results header. This helps you optimize query performance.

AI Query Generator

The AI Query Generator allows you to describe your data needs in plain English and receive working SuiteQL queries. It supports seven AI providers including Anthropic, OpenAI, Cohere, xAI/Grok, Google Gemini, Mistral AI, and OpenAI-compatible endpoints.

Getting Started with AI

1

Configure Your API Key

Click the AI button in the toolbar, then click the gear icon to open settings. Select your provider, enter your API key, and choose a model.

2

Describe Your Query

Type a natural language description of the data you need. For example: "Show me all active customers with their sales rep" or "Find invoices from last month over $1000".

3

Insert and Run

Click Insert Query to add the generated SQL to the editor. Enable Auto-execute query to run it immediately.

Features

Tips for Better Results

Tip: Get your API key from Anthropic Console, OpenAI Platform, Cohere Dashboard, xAI Console, Google AI Studio, or Mistral Console.

AI-Enhanced Features

Beyond the conversational AI Query Generator, the tool offers several AI-powered features integrated directly into the editor toolbar.

Natural Language Query Bar

Click the Ask button in the toolbar to toggle the natural language query bar. This provides a quick way to generate queries without opening the full AI modal:

Your visibility preference is saved, so the bar will remember whether you prefer it shown or hidden.

Explain Query

Click the Explain button (lightbulb icon) to have AI analyze your current query and explain it in plain English. This is useful for:

The explanation covers: what data is retrieved, tables used, joins and their purpose, filter conditions, and sorting/grouping.

Validate Query

Click the Validate button (shield icon) before running your query to have AI check for potential issues:

The validation panel shows issues found and suggestions for improvement, with options to "Run Anyway" or close.

Query Optimization Suggestions

When a query takes longer than 5 seconds to execute, a banner appears offering AI optimization suggestions:

Tip: All AI features require API key configuration. Click the AI button and then the gear icon to set up your credentials for any of the seven supported providers.

Tables Reference

Click Tables in the toolbar to open the Tables Reference in a new window. This powerful tool helps you explore NetSuite's database schema with AI assistance.

Basic Features

AI-Powered Table Search

Toggle to AI Find mode to search for tables using natural language:

Ask AI About This Table

When viewing any table's details, you'll see an "Ask AI About This Table" section with preset questions:

Generate Query from Selection

Build queries by selecting columns from the table detail view:

1

Select Columns

Use the checkboxes next to each column to select the fields you want. Use "Select All" or "Clear" for quick selection.

2

Generate Query

Click the Generate Query button. AI will create a practical query with your selected columns, including appropriate WHERE conditions and JOIN suggestions.

Tip: The Tables Reference shares AI settings with the main query tool, so you only need to configure your API key once.

Schema Explorer

The Schema Explorer builds a complete picture of your NetSuite database schema, respecting your role-based permissions. Access it from the Tables button dropdown or from within the Tables Reference.

Building Your Schema

Click Schema Explorer to open the tool. The first time you use it, click Build Schema to scan all available tables. This process:

Export Formats

Once your schema is built, you can export it in multiple formats:

The export grid shows common formats by default. Click "Show All Formats" to reveal advanced export options.

ERD Generation

Generate interactive Entity Relationship Diagrams directly in the browser:

Schema-Based Autocomplete

Enable "Use full schema" in the Options panel (under Autocomplete) to leverage your Schema Explorer data for enhanced autocomplete:

Tip: Build your schema once, then enable "Use full schema" for comprehensive autocomplete across your entire NetSuite database.

Document Generator

The Document Generator creates formatted PDF and HTML documents from your query results using FreeMarker/XML templates.

Template Editor

The template editor includes a full-featured CodeMirror toolbar:

AI Template Generation

Click AI Generate to create templates using natural language:

Template Refinement

When your editor has existing code, the AI modal switches to Refine mode:

Generate Suitelet

Click Generate Suitelet to create a standalone SuiteScript 2.1 Suitelet from your current template and queries:

The generated Suitelet includes a CONFIG object for easy customization and is ready to deploy in NetSuite.

Charts / Data Visualization

Visualize your query results with interactive charts powered by Chart.js.

Creating Charts

After running a query, click the Chart button in the results toolbar to open the chart configuration panel:

Using AI for Charts

Click AI Generate in the chart panel to describe what you want to visualize:

AI automatically selects the appropriate chart type and column mappings based on your data.

Exporting Charts

Click Export as PNG to save your chart as an image file for use in reports and presentations.

Tip: The chart feature automatically detects numeric columns in your results, making it easy to identify which columns can be used as values.

Plugin Architecture

Extend the SuiteQL Query Tool with custom plugins. Plugins can add UI elements, hook into query execution, and process results.

Enabling Plugins

To enable plugin support, set the PLUGIN_FOLDER_ID in the script's CONFIG object to the internal ID of a File Cabinet folder containing your plugin files:

const CONFIG = Object.freeze({
    // ... other config options ...
    PLUGIN_FOLDER_ID: 12345,  // File Cabinet folder ID
});

Plugin File Format

Plugin files must be named with the extension .sqt-plugin.js or .sqt-plugin.json. The tool automatically discovers and loads all plugin files in the specified folder.

Server-Side Hooks

Plugins can implement server-side hooks to process queries:

Client-Side Hooks

Plugins can respond to client events:

UI Injection Points

Plugins can inject custom UI elements at 17 predefined locations:

Plugin API

Plugins have access to the public API through the SQT namespace:

Feature Disabling

Plugins can disable built-in features using the disables[] array. This allows plugins to replace or hide default functionality. Over 20 features can be disabled including AI, export, history, and more.

Tip: A sample plugin (query-logger.sqt-plugin.js) is included with the tool demonstrating server/client hooks, UI injection, and settings management. See the PLUGIN-GUIDE.md file for complete documentation.

Configuration Options

Click the Options button in the toolbar to access configuration settings:

Pagination

Display Options

NULL Display

Script Configuration

Advanced users can modify the CONFIG object at the top of the script file:

const CONFIG = Object.freeze({
    VERSION: '2026.1',
    DATATABLES_ENABLED: true,
    REMOTE_LIBRARY_ENABLED: true,
    ROWS_RETURNED_DEFAULT: 100,
    QUERY_FOLDER_ID: null,  // Set to enable local library
    PLUGIN_FOLDER_ID: null,  // Set to enable plugin loading
    WORKBOOKS_ENABLED: false,
    MAX_HISTORY_ENTRIES: 50,
    SLOW_QUERY_THRESHOLD_MS: 3000,  // Show optimization banner after this
    AI_ENABLED: true,  // Master switch for all AI features
    AI_RESULTS_CHAT_ENABLED: false  // Allow AI to analyze results
});

AI Configuration Options

Plugin Configuration

Troubleshooting

Common Issues

"Invalid search filter" or similar errors

This usually indicates a syntax error in your SuiteQL query. Check for:

Query returns no results

Performance issues with large datasets

Auto-complete not working

Important: SuiteQL has some limitations compared to standard SQL. Not all SQL functions are supported, and some NetSuite-specific syntax may be required. Refer to NetSuite's SuiteQL documentation for details.

Getting Help

For additional help: